Skip to content

feat: connect to a linked environment from its read-only thread - #39439

Open
juliusmarminge wants to merge 3 commits into
t3code/links/read-linked-threadsfrom
t3code/links/connect-to-interact
Open

juliusmarminge wants to merge 3 commits into
t3code/links/read-linked-threadsfrom
t3code/links/connect-to-interact

Conversation

@juliusmarminge

@juliusmarminge juliusmarminge commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Stacked on #39406.

Problem

#39406 lets a client connected to environment A read a thread that lives on a linked environment B, but only read it. To reply, approve or stop the thread, the user had to leave the read-only view, find B's address, create a pairing code on B and add B by hand.

What this does

The read-only view gets one action, Connect to interact. It is the primary action of the bar that stands where a composer would (the read-only bar #39406 shares with subagent threads). Since #39406 was reworked the linked view is the thread's own stream drawn by the standard timeline, so on web the bar is LinkedThreadPane's ReadOnlyComposerBar below ReadOnlyThreadTimeline in the linked-thread right panel tab (and below the loading or error state before the first snapshot), and on mobile it is the bar under the sheet's read-only list. What comes of it shows as a notice on that same bar: "Connecting to fs-17…" while pairing, the unreachable message, and on web a "needs a pairing code" notice with Enter code that reopens the pre-filled dialog. Nothing is in the view's header.

  1. One step, when A's link to B is full-access. The client asks A (peerLinks.pairClient). A asks B over its link for a one-time pairing credential for that client and returns it with the addresses it reaches B at. The client checks which address answers it as B, pairs there exactly as it does from a pairing link, saves B as an environment and opens the same thread. No code is shown or typed. On web the thread opens in the main view, the way any thread on a connected environment does and the way the existing resolver opens this one from now on, and its read-only tab closes; on mobile the sheet closes and the thread opens.
  2. Otherwise (link below full access, B from before this, B refused, B unreachable from A, or the client may not manage access on A) the existing add-environment flow opens for B, with an address filled in where one is known and B's name in the title, asking for a pairing code the user creates on B. It is the same flow, not a second dialog.

If no address of B answers the client, the bar says "fs-17 is not reachable from this device" and the view stays read-only. If the client is already connected to B the read-only view never opens (the existing resolver sends it to the thread there), so the action is not offered.

How B exposes it

A dedicated HTTP route, POST /api/peer-link/client-pairing, authenticated by the link's own session.

Link sessions were /mcp-only. The alternative was a guarded MCP tool hidden from tool listings. I chose the route because a tool is reachable by anything that can call /mcp, which includes every thread credential an agent holds, and hiding a tool from listings is only discovery. The route never consults the thread-credential registry, so no agent on B, link-started or not, can authenticate to it, and nothing appears in any model's tool list. No model-facing tool text changed.

Security rules and where each is enforced

Rule Enforced
Full-access links only On B, in PeerClientPairingIssuer.issue: the caller must be a peer-link session whose access is full-access, and an administrator's runtime-mode ceiling below full access also refuses. A skips the round trip for a lower link, but B does not rely on that.
A person triggers it On A it is a client WebSocket RPC behind access:write (CLIENT_GUARDED_RPC_SCOPES). It is not an MCP tool on either side. B's route refuses any caller that is not a full-access peer-link session: other MCP clients get 403; thread credentials, ordinary client sessions and no credential get 401; a browser Origin gets 403.
Never more than the client has on A B grants the client's scopes on A intersected with AuthStandardClientScopes. The credential is one-time and lasts 3 minutes. Its label is <client> · via <A>, so B's Sharing & access shows where it came from, and it is revoked there like any other.
The credential stays out of logs, traces and events It travels only in the route's response and the RPC's result. Spans carry no arguments or results, the route answers no-store, and A drops the cause of an unreadable response instead of logging it. Nothing is written to a thread or persisted event.
Labs gate and old B Both sides check the Linked environments setting. B advertises linkClientPairing; A answers a typed unsupported / version without calling a B that lacks it.

Rationale kept in a code comment and in docs/internals/environment-auth.md: a full-access link's agents already run as B's user and could run t3 auth pairing create themselves, so minting here adds no power. Any lower link would gain some.

Scope

Maintainer feature work, requested by Julius as a follow-up to the Linked environments beta that shipped in #16653–#17130. It is not an outside contribution.

Tested

Server, A and B as real layers in one process on a TestClock (apps/server/src/peer/PeerClientPairing.test.ts):

  • full-access link → credential minted, labelled Phone · via Laptop, redeemable once, carrying only the client's scopes on A (and none outside a normal pairing); an unredeemed one is dead after 3 minutes
  • read-only, approval-required and auto links → unsupported from A without contacting B, and 403 from B when A is bypassed with the link's own token
  • a non-link MCP client at full access → 403; an agent's thread credential, an ordinary client session and no credential → 401; a browser origin → 403
  • Labs off on B → refused; Labs off on A → disabled
  • B without the capability → unsupported / version, and B is never asked

RpcAuthorization.test.ts: a client without access:write on A is refused before the handler runs.

Client (packages/client-runtime/src/linkedThread.test.ts): one step vs fallback, which address is used, and the unreachable case spending nothing.

Rebased onto the reworked #39406 (the linked thread is now the standard thread stream). The server side is unchanged. The client action and notices moved into the new view components with no change in behaviour; nothing of the deleted paged transcript is left in this PR. Rerun after the rebase: vp run check:changed, vp run i18n:check, the six server test files this touches (85 tests), and AddEnvironmentDialog.browser.test.tsx.

Surfaces

  • Server: A and B, done.
  • Web / desktop: the bottom bar's action and its notices (pairing, unreachable, pairing code needed), prefilled add-environment dialog, all locales. Done. The notice is kept with the tab for five minutes, so it is still there after the visit to Settings.
  • Mobile: the bottom bar's action, pairing and unreachable notices above it, and the add-environment screen opened for that machine, all locales. Done. The screen takes the machine's address from app state the sheet sets, never from the route, so a deep link cannot supply an address for the user to send a pairing code to.

Not included: after the manual fallback succeeds the user opens the thread again themselves (its link now resolves to B directly); the one-step path opens it for them.

Web, run for real between two dev servers named nucbox and fs-17, with nucbox holding a full-access link to fs-17 over its tailnet address. The browser was paired with nucbox only.

These screenshots are out of date. They show the paged transcript that #39406 no longer has; the body above the bar is now the standard timeline. The bar, its action and the result are the same.

Before: fs-17's thread, read through nucbox, with the action in the bottom read-only bar After one click: the browser is paired with fs-17 and the thread is open there
Right-panel tab with the read-only bar and Connect to interact The same thread open on fs-17 with a working composer

No pairing code was shown or typed. On fs-17 the new client is listed as Chrome on Linux · via cups (the link was made from a shell outside the renamed test host, hence "cups"). Mobile has not been run on a device.

Latest real run

Run for real after the rebase onto the single-stream base: clicking "Connect to interact" in the bottom bar paired the browser with fs-17 with no code shown and opened the thread there in the main view.

The right panel with a subagent tab and a linked-thread tab; the linked thread uses the normal timeline with a read-only bar

Claude Fable 5.2, Claude Code in T3 Code

🤖 Generated with Claude Code

@github-actions github-actions Bot added vouch:trusted Author is trusted by repo permissions or the VOUCHED list. size:XL 500-999 changed lines (additions + deletions). size:XXL 1,000+ changed lines (additions + deletions). and removed size:XL 500-999 changed lines (additions + deletions). labels Nov 19, 2026
@juliusmarminge
juliusmarminge force-pushed the t3code/links/connect-to-interact branch from 22502d9 to 4bdb4ec Compare November 20, 2026 00:10
@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider Metric Main baseline This PR Impact PR ceiling
Codex Total thread wire — 5.0 KiB — 6.8 KiB ✅
Codex Thread snapshot wire — 3.8 KiB — 4.9 KiB ✅
Codex Live turn WebSocket wire — 1.2 KiB — 2.0 KiB ✅
Codex Live turn WebSocket decoded — 21.5 KiB — 24.4 KiB ✅
Codex Live turn messages — 1 — 8 ✅
Claude Total thread wire — 5.0 KiB — 6.8 KiB ✅
Claude Thread snapshot wire — 3.8 KiB — 4.9 KiB ✅
Claude Live turn WebSocket wire — 1.2 KiB — 2.0 KiB ✅
Claude Live turn WebSocket decoded — 21.9 KiB — 24.4 KiB ✅
Claude Live turn messages — 1 — 8 ✅

Other scenarios

No main baseline exists yet for these 64 scenario measurements.

All 64 scenario measurements
Provider Scenario Metric Main baseline This PR Impact PR ceiling
Codex short turn resume WebSocket decoded — 10.5 KiB — 12.7 KiB ✅
Codex short turn resume WebSocket messages — 2 — 2 ✅
Codex long turn running, cold open HTTP decoded — 281.7 KiB — 302.7 KiB ✅
Codex long turn running, cold open rows — 75 — 75 ✅
Codex long turn running, history page HTTP decoded — 92.4 KiB — 107.4 KiB ✅
Codex long turn running, history page rows — 75 — 75 ✅
Codex long turn finished, cold open HTTP decoded — 381.5 KiB — 410.2 KiB ✅
Codex long turn finished, cold open rows — 151 — 151 ✅
Codex long turn finished, socket cold open WebSocket decoded — 381.6 KiB — 410.2 KiB ✅
Codex long turn finished, socket cold open WebSocket messages — 2 — 2 ✅
Codex long turn finished, socket cold open rows — 151 — 151 ✅
Codex long turn finished, work page HTTP decoded — 186.2 KiB — 200.2 KiB ✅
Codex long turn finished, work page rows — 150 — 150 ✅
Codex idle thread resume WebSocket decoded — 65 B — 200 B ✅
Codex idle thread resume WebSocket messages — 1 — 1 ✅
Codex fleet shell snapshot HTTP decoded — 42.4 KiB — 53.7 KiB ✅
Codex fleet shell snapshot rows — 27 — 27 ✅
Codex fleet shell subscribe WebSocket decoded — 65 B — 200 B ✅
Codex fleet shell subscribe WebSocket messages — 1 — 1 ✅
Codex fleet shell resume check HTTP decoded — 18 B — 100 B ✅
Codex fleet shell resume check rows — 0 — 0 ✅
Codex stale shell reload HTTP decoded — 42.4 KiB — 53.7 KiB ✅
Codex stale shell reload rows — 27 — 27 ✅
Codex stale shell resume WebSocket decoded — 140 B — 400 B ✅
Codex stale shell resume WebSocket messages — 2 — 2 ✅
Codex stale todo list cold open HTTP decoded — 72.4 KiB — 83.0 KiB ✅
Codex stale todo list cold open rows — 75 — 75 ✅
Codex stale todo list cold open nodes — 2 — 4 ✅
Codex stale todo list cold open subagents — 2 — 4 ✅
Codex stale todo list cold open plans — 1 — 2 ✅
Codex stale todo list cold open providerTurns — 1 — 2 ✅
Codex stale todo list cold open checkpoints — 1 — 2 ✅
Claude short turn resume WebSocket decoded — 10.6 KiB — 12.7 KiB ✅
Claude short turn resume WebSocket messages — 2 — 2 ✅
Claude long turn running, cold open HTTP decoded — 283.3 KiB — 302.7 KiB ✅
Claude long turn running, cold open rows — 75 — 75 ✅
Claude long turn running, history page HTTP decoded — 93.4 KiB — 107.4 KiB ✅
Claude long turn running, history page rows — 75 — 75 ✅
Claude long turn finished, cold open HTTP decoded — 384.2 KiB — 410.2 KiB ✅
Claude long turn finished, cold open rows — 151 — 151 ✅
Claude long turn finished, socket cold open WebSocket decoded — 384.3 KiB — 410.2 KiB ✅
Claude long turn finished, socket cold open WebSocket messages — 2 — 2 ✅
Claude long turn finished, socket cold open rows — 151 — 151 ✅
Claude long turn finished, work page HTTP decoded — 188.1 KiB — 200.2 KiB ✅
Claude long turn finished, work page rows — 150 — 150 ✅
Claude idle thread resume WebSocket decoded — 66 B — 200 B ✅
Claude idle thread resume WebSocket messages — 1 — 1 ✅
Claude fleet shell snapshot HTTP decoded — 43.0 KiB — 53.7 KiB ✅
Claude fleet shell snapshot rows — 27 — 27 ✅
Claude fleet shell subscribe WebSocket decoded — 66 B — 200 B ✅
Claude fleet shell subscribe WebSocket messages — 1 — 1 ✅
Claude fleet shell resume check HTTP decoded — 18 B — 100 B ✅
Claude fleet shell resume check rows — 0 — 0 ✅
Claude stale shell reload HTTP decoded — 43.0 KiB — 53.7 KiB ✅
Claude stale shell reload rows — 27 — 27 ✅
Claude stale shell resume WebSocket decoded — 140 B — 400 B ✅
Claude stale shell resume WebSocket messages — 2 — 2 ✅
Claude stale todo list cold open HTTP decoded — 73.4 KiB — 83.0 KiB ✅
Claude stale todo list cold open rows — 75 — 75 ✅
Claude stale todo list cold open nodes — 2 — 4 ✅
Claude stale todo list cold open subagents — 2 — 4 ✅
Claude stale todo list cold open plans — 1 — 2 ✅
Claude stale todo list cold open providerTurns — 1 — 2 ✅
Claude stale todo list cold open checkpoints — 1 — 2 ✅

Baseline: unavailable · PR result: 091cf25 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

  • Codex decoded thread snapshot: 108.5 KiB
  • Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

@juliusmarminge
juliusmarminge force-pushed the t3code/links/connect-to-interact branch 2 times, most recently from 3c7d79f to 22ba699 Compare November 20, 2026 03:23
@juliusmarminge
juliusmarminge force-pushed the t3code/links/connect-to-interact branch 2 times, most recently from eac3dc2 to 79192bf Compare November 20, 2026 06:34
juliusmarminge and others added 3 commits November 19, 2026 23:06
… linked environment

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@juliusmarminge
juliusmarminge force-pushed the t3code/links/connect-to-interact branch from 79192bf to 091cf25 Compare November 20, 2026 07:07

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size:XXL 1,000+ changed lines (additions + deletions). vouch:trusted Author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant